ZapDS 0.24 help file
 Darren Salt, 1996

This software is COPYRIGHT, but has been released as FREEWARE. Please see the
end of this file for conditions of use and distribution.


For commands where no syntax is given, this is because they take no
parameters!

Any commands which take a string parameter will open the minibuffer if no
parameter is supplied.


DS_RunApp

Will save the file if changes have been made, then tries to run it as an
application (also sends the window to the back) - AFTER Shift & Ctrl are
released (if they were pressed). For example:
  File being edited  File actually run  Notes
  !Beep.!RunImage    !Beep.!Run		Runs !Beep.!RunImage if not found
  !Beep.Data.Make    !Beep.Data.Make
  Text.Build	     Text.Build


DS_Insert

Inserts a space at the cursor as in !Edit.
In byte mode, inserts a zero byte.
In word mode, inserts a zero word.
In code mode, inserts a DCD 0.


DS_Eval

Evaluates the supplied expression and inserts the signed result in the
supplied base at the cursor position. If the expression evaluates to a
string, the base (if supplied) is ignored.

Syntax: DS_Eval "<base>:<expression>"
    or: DS_Eval "<expression>"

For numeric expressions:

Valid base values are between 2 and 36. In the second form, the base defaults
to decimal.

  Examples:		C	BASIC	Others
	16:160*1024	0x28000	&28000	&28000
	640-16		624	624	624
	36:123456	36_2N9C	36_2N9C	36_2N9C
	2:27	 	0b11011	%11011	2_11011

Exceptions:

In byte mode, only the bottom byte of the result is used. For example, if
DS_EVAL "123" is executed then the byte &7B ('{') is inserted. The base is
ignored.

In word and code modes, the result is inserted as a hex word, much like DCD
in assembler, but reversed if the 'big endian' flag is set. The base is
ignored.

For these modes, or for string expressions, it does not matter whether you
use DS_Eval, DS_UEval or DS_EvalH since they will function identically.


DS_UEval

Like DS_Eval but the result is unsigned. Similar syntax.


DS_EvalH

Like DS_Eval but the result is always unsigned hexadecimal.

Syntax: DS_EvalH "<expression>"


DS_AdrL

Assembles a long (two instruction) ADR.

Syntax: DS_AdrL "[<condition code>] <register>,<address>"

Example:
	at address &1000, the command
		DS_AdrL "LT R1,&5344"
	is equivalent to
		Assemble "ADRLT R1,&1344"
		Assemble "ADDLT R1,R1,#&4000"
(It will of course use SUB if required.)


DS_AdrX

Assembles a very long (three instruction) ADR, much as DS_AdrL does - it even
has the same syntax.


DS_FindFile

Looks for an object name (file or directory) at the cursor. If a file name is
found, then it attempts to load the named file - if nothing appears to
happen, this is because the file is already loaded. If a directory name is
found, then it is opened using *Filer_OpenDir.

A name may not contain control codes, spaces, or one of " # * |. These, along
with start and end of file, are taken as the delimiting characters. For
example, executing DS_FindFile with the cursor somewhere in the middle of
*<Zap$Dir>.Fonts.* causes the directory <Zap$Dir>.Fonts to be opened. Note
that the trailing dot is ignored.

Slight cheat: even if nothing is found with the given name, Zap_FindFile is
called in order to expand the name to a full pathname and report an error.


DS_OpenParent

Opens the directory containing the current file - just like clicking
Shift-Adjust on the close icon!


DS_SwapCaseCursor

Swaps the case of the letter at the cursor, advancing the cursor by one
character - whether there is a selection or not.


DS_SaveKeepStamp

Saves the file immediately (ie. no prompt), but preserves the datestamp
regardless of whether the file has changed or not.

If the file does not have a complete pathname, it is not saved - you will
hear a beep instead.


DS_StripCtrlCodes

Strips all control codes (except for the current tab and return characters)
from a file, and removes everything from the first ctrl-Z onwards. These effects are, of course, optional.

Syntax: DS_StripCtrlCodes <action>

The following values of 'action' are defined:

Bit 0 set: strip all control codes
Bit 1 set: strip all control codes except ctrl-G [bell], ctrl-H [backspace]
	   and ctrl-L [form feed]
bit 2 set: remove everything from the first ctrl-Z [soft-EOF]

The default parameter value is 5.

Other values are masked so that only the above values may occur.

If control code stripping is selected, then the 'DOS text file' and 'spool
file' flags are also cleared.

The cursor may be moved by this command: this one small feature not
implemented = vast speed improvement.

This command will not operate in byte, word, code or BASIC modes (it will
beep at you instead).


DS_Untabify

Converts tabs to spaces, whilst maintaining the formatting - thus reversing
the effects of StripSpaces 4.

In BASTXT, CMode, C, Pascal, and Assembler modes, tabs enclosed in double
quotes " are left intact.

The cursor may be moved by this command: this one small feature not
implemented = vast speed improvement.

This command will not operate in byte, word, code or BASIC modes (it will
beep at you instead).


DS_MessageID

Generates a new date and message ID from the real-time clock and the e-mail
address in the "From:" line.

The "From:" line must be in either of the two commonly-used formats:
	From: arcsalt@spuddy.mew.co.uk (Darren Salt)
	From: Darren Salt <arcsalt@spuddy.mew.co.uk>

The "Date: " and "Message-ID: " header lines must be present - *including*
the space; the rest of these lines is ignored.

No action is taken if any of the required lines are missing or badly formed.

I cannot guarantee that the message ID is unique, but the fact that it
includes the CRC of the e-mail address helps!

This command only works in 'Email' mode.


DS_StripCtrlWithMask

Like DS_StripCtrlCodes, but much more flexible...

The command takes one parameter (evaluated via OS_EvaluateExpression - think
*Eval if you don't know that SWI), in which bit x (if set) causes all
occurrences of character code x to be removed from the file.

The default parameter, if 0 is supplied, is to strip all control codes except
\a (\7), \b (\8), \f (\12), and the current return and tab characters.

The cursor may be moved by this command: this one small feature not
implemented = vast speed improvement.

This command will not operate in byte, word, code or BASIC modes (it will
beep at you instead).

Syntax: DS_StripCtrlWithMask "<mask_word>"

For example, to strip ASCII codes 1, 2, 3, 6 and 21:
	DS_StripCtrlWithMask "2_00000000001000000000000001001110"
or	DS_StripCtrlWithMask "&0020004E"
or	DS_StripCtrlWithMask "1<<21 OR 1<<6 OR 1<<3 OR 1<<2 OR 1<<1"


DS_Add, DS_Sub, DS_Rsb, DS_And, DS_Or, DS_Eor
          
These commands perform an arithmetic or logic operation on the current byte
(or word, if in word or code mode). Each takes a string parameter, evaluating
to a number.

For example, to add &180 to a word (in word mode), you'd use
	DS_Add "&180"


DS_SWItoName

This takes an SWI number, found at the cursor position, and replaces it with
the corresponding name.


DS_SWItoNumber

This takes an SWI name, found at the cursor position, and replaces it with
the corresponding number.


DS_ToIcon

This tries to insert the selected text somewhere by pretending you typed it.
It waits for you to click Select or Adjust (preferably on a writeable
icon...!), then flushes the keyboard buffer and, if Adjust is used, inserts a
ctrl-U. It then inserts the selection (stopping at the first control code).

Clicking Menu, or pressing any key, will cancel.


DosTextFile and SpoolFile
	
Both commands have been deleted at the suggestion of Chris Manning
(chrism@spuddy.mew.co.uk)
For DosTextFile or FFlags_Toggle &1B, use FFlags_Toggle &DD1B
For SpoolFile	or FFlags_Toggle &1D, use FFlags_Toggle &DB1D



Copyright

The conditions of copying this program and its associated documentation are
the same as those of the main Zap application, except you do not need my
permission to copy it if you have Dominic Symes's.

This software is provided as is with no warranty as to its suitability or
otherwise for any particular task. If it does anything nasty then I want to
know so I can fix it, but I'm not taking any responsibility. (Besides,
there's no point in sueing me since I've got no money.)

Please note that I reserve the right to make alterations to this program, its
operation, documentation, and/or conditions of use without notice in any way
I see fit. Hopefully it will be an improvement.


Contact

arcsalt@spuddy.mew.co.uk
